First-order perturbation
=========================

The state vector
-----------------

.. math::

    z_{t}\equiv\left[
    \begin{array}{ccc}
    x_{t-1}^{\prime} & \sigma & \varepsilon_{t}^{\prime}
    \end{array}
    \right]^{\prime}

where :math:`\sigma` is the perturbation parameter.

In some applications, agents have information on shocks
:math:`k \geq 0` periods ahead. The state vector under
anticipated shocks (Maih, 2010; Juillard and Maih, 2010) is:

.. math::

    z_{t}\equiv\left[
    \begin{array}{cccccc}
    x_{t-1}^{\prime} & \sigma & \varepsilon_{t}^{\prime} & \varepsilon_{t+1}^{\prime} & \cdots & \varepsilon_{t+k}^{\prime}
    \end{array}
    \right]^{\prime}


Solvers for the quadratic matrix polynomial
--------------------------------------------

Constant-parameter case (and the Maih-Waggoner perturbation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The algorithms for solving linear rational expectations models:

* ``rise_1`` -- a Klein-like algorithm. Default.
* ``sims`` -- the Gensys algorithm of Sims (2002).
* ``klein`` -- the algorithm of Klein (2000).
* ``AIM`` -- see Anderson (2008).
* ``cyclic_reduction`` -- the cyclic-reduction algorithm.

.. note::

   If there is a unique and stable solution in the Maih-Waggoner
   perturbation, these algorithms also work in the
   regime-switching case.

Regime-switching case
~~~~~~~~~~~~~~~~~~~~~~

The algorithms for solving regime-switching linear rational
expectations models:

* ``mnk`` -- Newton (Maih, 2015), explicitly forming Kronecker
  products.
* ``mn`` -- Newton (Maih, 2015) avoiding Kronecker products;
  more efficient on large systems.
* ``fwz`` -- Newton (Farmer, Waggoner and Zha, 2011).
* ``dsge_udc`` -- undetermined coefficients (Maih-Waggoner,
  2018). Only with the Maih-Waggoner perturbation.
* ``dsge_schur`` -- Schur-based method (Maih-Waggoner, 2018).
  Returns the most stable solution; equivalent to ``rise_1`` and
  the constant-parameter solvers when a unique stable solution
  exists. Only with the Maih-Waggoner perturbation.
* ``dsge_groebner`` -- Groebner-basis solver from computational
  algebraic geometry (Maih-Waggoner, 2018). When it works, finds
  all possible solutions.
* ``mfi`` -- functional iteration (Maih, 2015).

.. note::

   All these regime-switching solvers can solve constant-
   parameter models even when there is no unique and stable
   solution.

See :doc:`Solving` for the diagnostic protocol when a solver
returns retcode 21.


User-defined solver
--------------------

A user-defined solver should be a function with signature::

    [Tz_pb, Tsig, Te, retcode] = ...
        user_solver(Gplus01, A0, Aminus, B, Q, stst_, vargs{:});

Inputs:

* ``Gplus01`` -- ``nd x nd x h x h`` array of forward-looking
  coefficient matrices multiplied by the transition probabilities.
* ``A0`` -- ``nd x nd x h`` array of contemporaneous coefficient
  matrices.
* ``Aminus`` -- ``nd x nd x h`` array of backward-looking
  coefficient matrices.
* ``B`` -- ``nd x nx x h`` array of shock coefficient matrices.
* ``Q`` -- ``h x h`` transition matrix with ``Q(i,j)`` the
  probability of going from regime ``i`` to regime ``j``.
* ``stst_`` -- ``nd x h`` matrix whose columns are the steady
  state in each regime.
* ``vargs`` -- any additional arguments.

Outputs:

* ``Tz_pb`` -- ``nd x nd x h`` array, impact of autoregressive
  terms.
* ``Tsig`` -- ``nd x nd`` matrix, impact of the perturbation
  parameter in each regime.
* ``Te`` -- ``nd x nx x h`` array, impact of shocks.
* ``retcode`` -- ``0`` if no problem, non-zero otherwise.